Bitmaps and Pixel Maps (IM: QD3D)

Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 4 - Geometric Objects / Geometric Objects Reference

Bitmaps and Pixel Maps
QuickDraw 3D defines bitmaps and pixmaps to specify the images used to define markers, textures, and other objects. A bitmap is a two-dimensional array of values, each of which represents the state of one pixel. A bitmap is defined by the TQ3Bitmap data type.
typedef struct TQ3Bitmap {
   unsigned char              *image;
   unsigned long              width;
   unsigned long              height;
   unsigned long              rowBytes;
   TQ3Endian                  bitOrder;
} TQ3Bitmap;
Field Description

image
The address of a two-dimensional block of memory that contains the bitmap image. The size, in bytes, of this block must be exactly the product of the values in the height and rowBytes fields.
width
The width, in bits, of the bitmap.
height
The height of the bitmap.
rowBytes
The distance, in bytes, from the beginning of one row of the image data to the beginning of the next row of the image data. Each new row in the image begins at an unsigned character that follows (but not necessarily immediately follows) the last unsigned character of the previous row. The minimum value of this field is the size of the image (as returned, for example, by the Q3Bitmap_GetImageSize function) divided by the value of the height field.
bitOrder
The order in which the bits in a byte are addressed. This field must contain one of these constants:
               typedef enum TQ3Endian {
                  kQ3EndianBig,
                  kQ3EndianLittle
               } TQ3Endian;
The constant kQ3EndianBig indicates that the bits are addressed in a big-endian manner. The constant kQ3EndianLittle indicates that the bits are addressed in a little-endian manner.
A pixel map (or, more briefly, a pixmap) is a two-dimensional array of values, each of which represents the color of one pixel. A pixmap is defined by the TQ3Pixmap data type.
typedef struct TQ3Pixmap {
   void                       *image;
   unsigned long              width;
   unsigned long              height;
   unsigned long              rowBytes;
   unsigned long              pixelSize;
   TQ3PixelType               pixelType;
   TQ3Endian                  bitOrder;
   TQ3Endian                  byteOrder;
} TQ3Pixmap;
Field Description

image
The address of a two-dimensional block of memory that contains the pixmap image. The size, in bytes, of this block must be exactly the product of the values in the height and rowBytes fields.
width
The width, in pixels, of the pixmap.
height
The height, in pixels, of the pixmap.
rowBytes
The distance, in bytes, from the beginning of one row of the image data to the beginning of the next row of the image data. The minimum value of this field depends on the values of the width and pixelSize fields. You can use the following C language macro to determine a value for this field:
               #define Pixmap_GetRowBytes(width, pixelSize) \ 
                     ((pixelSize) < 8) \ 
                     ? (((width) / (8 / (pixelSize))) + \ 
                     ((width) % (8 / (pixelSize)) > 0)) \ 
                     : (width * ((pixelSize) / 8))
pixelSize
The size, in bits, of a pixel.
pixelType
The type of a pixel. This field must contain one of these constants (which must match the size specified in the pixelSize field):
               typedef enum TQ3PixelType {
                  kQ3PixelTypeRGB32    /*32 bits per pixel*/
               } TQ3PixelType;
bitOrder
The order in which the bits in a byte are addressed. This field must contain one of these constants:
               typedef enum TQ3Endian {
                  kQ3EndianBig,
                  kQ3EndianLittle
               } TQ3Endian;
The constant kQ3EndianBig indicates that the bits are addressed in a big-endian manner. The constant kQ3EndianLittle indicates that the bits are addressed in a little-endian manner.
byteOrder
The order in which the bytes in a word are addressed. This field must contain kQ3EndianBig or kQ3EndianLittle.
A storage pixel map (or, more briefly, a storage pixmap) is a pixmap whose data is contained in a storage object. A storage pixmap is defined by the TQ3StoragePixmap data type.
typedef struct TQ3StoragePixmap {
   TQ3StorageObject           image;
   unsigned long              width;
   unsigned long              height;
   unsigned long              rowBytes;
   unsigned long              pixelSize;
   TQ3PixelType               pixelType;
   TQ3Endian                  bitOrder;
   TQ3Endian                  byteOrder;
} TQ3StoragePixmap;
Field Description

image
A storage object that contains the pixmap image. The size, in bytes, of this file must be exactly the product of the values in the height and rowBytes fields.
width
The width, in pixels, of the pixmap.
height
The height, in pixels, of the pixmap.
rowBytes
The distance, in bytes, from the beginning of one row of the image data to the beginning of the next row of the image data. The minimum value of this field depends on the values of the width and pixelSize fields. You can use the following C language macro to determine a value for this field:
               #define Pixmap_GetRowBytes(width, pixelSize) \ 
                     ((pixelSize) < 8) \ 
                     ? (((width) / (8 / (pixelSize))) + \ 
                     ((width) % (8 / (pixelSize)) > 0)) \ 
                     : (width * ((pixelSize) / 8))
pixelSize
The size, in bits, of a pixel.
pixelType
The type of a pixel. This field must contain one of these constants (which must match the size specified in the pixelSize field):
               typedef enum TQ3PixelType {
                  kQ3PixelTypeRGB32    /*32 bits per pixel*/
               } TQ3PixelType;
bitOrder
The order in which the bits in a byte are addressed. This field must contain one of these constants:
               typedef enum TQ3Endian {
                  kQ3EndianBig,
                  kQ3EndianLittle
               } TQ3Endian;
The constant kQ3EndianBig indicates that the bits are addressed in a big-endian manner. The constant kQ3EndianLittle indicates that the bits are addressed in a little-endian manner.
byteOrder
The order in which the bytes in a word are addressed. This field must contain kQ3EndianBig or kQ3EndianLittle.